Add `dotnetup` Version Intent & Timeline Doc by nagilson · Pull Request #55390 · dotnet/sdk

nagilson · 2026-07-20T23:42:26Z

This document is meant to initiate conversations.

When polished, the document's function is to inform developers & customers using dotnetup what the intent will be of each dotnetup version, and the level of support it will receive (in terms of breaking change notices, bug fixes, and security updates.)

It is not an official support policy document. Such a document would be owned and persist on the https://dotnet.microsoft.com/en-us/platform/support/policy policy page. It contains my words which cannot and should not be defined as an official statement from Microsoft.

Please see #54735 for more details about specific release plans and a release strategy.

This is very much a draft and includes my own perspectives, it will evolve and mature before it is committed. Do not consume it as official `dotnet` policy at this time. The primary intent for this document is to start conversations about the official support policy, and then to create clarity around support and the potential for breaking changes amongst our customers who have started to try-out `dotnetup` off our internal `ci` branches. Please see dotnet#54735 for more details about specific release plans and a release strategy. We have not yet consulted with the release team on this particular doc.

azure-pipelines · 2026-07-20T23:42:42Z

Azure Pipelines: Successfully started running 2 pipeline(s). 1 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

This needs to be discussed broadly before it's a commitment.

…/nagilson/sdk into nagilson-dotnetup-support-policy

…official policy

…t preview policy docs state

…g doc We don't actually own those decisions on support policies and can't make them. The true intent here is to outline what the intent of each version is for us as developers (understanding when we can make a breaking change and when to document it) + communicate that outward.

azure-pipelines · 2026-07-22T21:32:36Z

Azure Pipelines: Successfully started running 2 pipeline(s). 1 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

Copilot

Pull request overview

Adds a new internal-facing documentation page under documentation/general/dotnetup/ to describe the intent and (non-official) support expectations for dotnetup build qualities/channels, to help developers/customers choose between daily, preview, and stable.

Changes:

Introduces a dotnetup version/channel intent + support-lifecycle overview document.
Documents intended platform/shell support scope and servicing expectations.
Adds an FAQ note on how to install stable once available via get-dotnetup scripts.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…ixes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

dsplaisted · 2026-07-24T18:38:18Z

@@ -0,0 +1,96 @@
+# `dotnetup` `daily`, `preview`, and `stable` Version Definitions


The document is still titled dotnetup-support-policy, consider renaming it.

dsplaisted · 2026-07-24T19:13:41Z

+Looking for the support policy for the .NET Platform? See the [.NET Support Policy](https://dotnet.microsoft.com/platform/support/policy) page.
+`dotnetup`'s official support policy document is still underway; here, we aim to communicate version intent to allow users to pick which version of `dotnetup` to use.


"Support" is an overloaded term, but in terms of the "support policy", what it means (according to copilot) is that Microsoft ships fixes and provides technical assistance for the product.

I think maybe we can drop this whole section (the reference to "support") from this document. I'm not sure though.

I think I'd like to leave one sentence mentioning this is NOT a support policy document, and to instead look elsewhere for clarity, but this can probably be cut down and seem less formalized, so it doesn't give the wrong impression

dsplaisted · 2026-07-24T19:21:57Z

+### Supported Platforms and Shells
+
+The latest `stable` version of `dotnetup` is supported on Windows, macOS, and Linux versions supported by its embedded .NET Runtime. See the [.NET supported operating system policy](https://github.com/dotnet/core/blob/main/os-lifecycle-policy.md) for the applicable operating system lifecycle rules.
+
+Shell integration, including profile modification and environment-script generation, is supported for Bash (`bash`), Z shell (`zsh`), fish (`fish`), and Windows PowerShell (`powershell`) alongside PowerShell Core (`pwsh`). Other shells are not yet supported for shell integration.


I'm not sure we need this section at all in a document describing our different release channels. To me it seems unnecessary to list the OS's and shells that are supported (in this document). It also introduces the "supported" term in a slightly different sense, in that the software "supports" (ie works with) a given OS or shell rather than that Microsoft "supports" (ie provides fixes and technical assistance for) the software.

I think this is helpful to communicate so we have 1 place to tell customers what we do and don't support, either for OS or for Shells. It's not a given to folks outside our area of influence know that dotnetup is even a cross platform product (imo). Also makes it clear we don't support any distro that the runtime does not support.

dsplaisted · 2026-07-24T19:23:49Z

+
+The `daily` `dotnetup` builds will use themselves to build. This allows us to catch problems early by dogfooding our own product.
+
+Multiple `daily` builds may be published in one day. Only the most recent `daily` build is intended for dogfooding; older `daily` builds are not maintained.


The second sentence here could possibly be deleted.

I see where you're coming from, whether this doc is the right place for this sentence is interesting. The intent here was the communicate that we shouldn't rely on the daily channel in daily CI because that would block other daily builds from fixing the daily build. I think we could leave it but I don't feel strongly.

dsplaisted · 2026-07-24T19:33:35Z

+`stable` builds will be built off of `stable` .NET Runtimes.
+The first runtime supporting a `stable` build will be `.NET 11`.


I think this is an interesting issue. If we're using a single branch, then once we go stable we can never build against a preview version of the .NET Runtime. Maybe that's a reason to consider multiple branches. I think this warrants more thought and team discussion.

I agree. This could be quite bad considering we needed .NET 11 SDK source code changes to make dotnetup work. Honestly, maybe I'm ok with trusting the preview runtime versions here in the stable version of dotnetup if it doesn't mean we're locked into essentially an 11 month time window where we cant use newer .net features or we need to service multiple branches.

dsplaisted · 2026-07-24T19:35:13Z

+`stable` builds will be built off of `stable` .NET Runtimes.
+The first runtime supporting a `stable` build will be `.NET 11`.
+
+`stable` versions of `dotnetup` follow the [.NET Runtime servicing policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core#servicing). When a .NET Runtime servicing release updates the runtime embedded in `dotnetup`, the corresponding `dotnetup` release may be published up to three days later. The current `stable` version of `dotnetup` remains supported during this publication window.


This is another interesting issue for discussion. I'm not sure we should put this policy in this document. I wonder if we will want to do internal builds of dotnetup ahead of each servicing release so that we can release dotnetup together with the runtime updates.

Right, 3 days is arbitrary. We have the power to coordinate with the runtime team though I imagine most CVEs won't really affect dotnetup. It's costly to check whether each one does because there are so many CVEs so we might as well just match the ship schedule.

dsplaisted · 2026-07-24T19:36:07Z

+#### Major `stable` Release
+
+Major releases may include new features and functionality, new public APIs, bug fixes, and intentional [breaking changes](https://learn.microsoft.com/dotnet/core/compatibility/breaking-changes).
+
+#### Minor `stable` Release
+
+Minor releases may include new features, functionality, APIs, or bug fixes, but their scope will be generally smaller than that of major releases.
+
+#### Patches & Servicing
+
+Patch versions may include security fixes, bug fixes, and updates to the self-contained .NET Runtime embedded in the executable. A patch version is not intended to introduce new features. A patch update to the embedded runtime causes a patch update to `dotnetup`.


As mentioned above, I'd consider dropping or cutting down this section. I'm not too sure though.

I think this section is important for external communication, though it's basically a redefinition of semver with some wiggle room

dsplaisted · 2026-07-24T19:36:56Z

+
+Patch versions may include security fixes, bug fixes, and updates to the self-contained .NET Runtime embedded in the executable. A patch version is not intended to introduce new features. A patch update to the embedded runtime causes a patch update to `dotnetup`.
+
+#### End of support


I'm not sure we need to cover the end of support in this document.

I thought about this too, though I think it's ideal to have a written down plan.

dsplaisted · 2026-07-24T19:38:01Z

+
+**How can I update to the latest `dotnetup` version?**
+
+Once `stable` releases are available, follow the [download instructions](README.md#download-dotnetup) and select the `stable` build quality. Pass `--quality stable` to `get-dotnetup.sh` or `-Quality stable` to `get-dotnetup.ps1`. Running either script without this option currently installs a `daily` build, which is available today but not supported.


We haven't implemented this yet, have we? I'm not sure we need to include this in the document especially when it's not yet implemented. By the time we go stable, we probably want dotnetup to be able to update itself.

Ok to remove this! And agreed.

Co-authored-by: Daniel Plaisted <dsplaisted@gmail.com>

nagilson commented Jul 20, 2026

View reviewed changes

Comment thread documentation/general/dotnetup/dotnetup-support-policy.md Outdated

nagilson added 8 commits July 20, 2026 16:43

Fix removed word

b80a57d

Mention how long dotnetup would receive support if it were deprecated

a26b61e

This needs to be discussed broadly before it's a commitment.

Merge branch 'nagilson-dotnetup-support-policy' of https://github.com…

d77b861

…/nagilson/sdk into nagilson-dotnetup-support-policy

Tighten verbage of support policy

4a08acc

mention daily builds may still receive breaking change notices

f8d2d4f

preview versions could be on a non preview .net

39e910c

Replace microsoft with .NET teams to clarify this is not a microsoft …

2880a7e

…official policy

Clarify noun of ownership of support policy

5781d68

nagilson requested a review from a team July 21, 2026 17:34

nagilson added 3 commits July 21, 2026 10:52

mention preview versions are offered for public testing just like .ne…

a40d40a

…t preview policy docs state

Clarify product timelines

7311c8b

nagilson changed the title ~~Add prototype dotnetup support policy doc~~ Add dotnetup Version Intent Doc Jul 22, 2026

nagilson changed the title ~~Add dotnetup Version Intent Doc~~ Add dotnetup Version Intent & Timeline Doc Jul 22, 2026

Merge branch 'release/dnup' into nagilson-dotnetup-support-policy

95b7657

nagilson marked this pull request as ready for review July 22, 2026 21:32

Copilot AI review requested due to automatic review settings July 22, 2026 21:32

Copilot started reviewing on behalf of nagilson July 22, 2026 21:32 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

nagilson and others added 2 commits July 22, 2026 14:36

Fix grammatical error

2297edd

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Address PR feedback: clarify title, dogfooding wording, and grammar f…

c299a51

…ixes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

dsplaisted reviewed Jul 24, 2026

View reviewed changes

remove term supported

f03a54b

Co-authored-by: Daniel Plaisted <dsplaisted@gmail.com>

		@@ -0,0 +1,96 @@
		# `dotnetup` `daily`, `preview`, and `stable` Version Definitions

		Looking for the support policy for the .NET Platform? See the [.NET Support Policy](https://dotnet.microsoft.com/platform/support/policy) page.
		`dotnetup`'s official support policy document is still underway; here, we aim to communicate version intent to allow users to pick which version of `dotnetup` to use.


		The `daily` `dotnetup` builds will use themselves to build. This allows us to catch problems early by dogfooding our own product.

		Multiple `daily` builds may be published in one day. Only the most recent `daily` build is intended for dogfooding; older `daily` builds are not maintained.

		`stable` builds will be built off of `stable` .NET Runtimes.
		The first runtime supporting a `stable` build will be `.NET 11`.


		Patch versions may include security fixes, bug fixes, and updates to the self-contained .NET Runtime embedded in the executable. A patch version is not intended to introduce new features. A patch update to the embedded runtime causes a patch update to `dotnetup`.

		#### End of support


		How can I update to the latest `dotnetup` version?

		Once `stable` releases are available, follow the [download instructions](README.md#download-dotnetup) and select the `stable` build quality. Pass `--quality stable` to `get-dotnetup.sh` or `-Quality stable` to `get-dotnetup.ps1`. Running either script without this option currently installs a `daily` build, which is available today but not supported.

Uh oh!

Conversation

nagilson commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

azure-pipelines Bot commented Jul 20, 2026

Uh oh!

Uh oh!

azure-pipelines Bot commented Jul 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nagilson commented Jul 20, 2026 •

edited

Loading